Qt GameEnabler
==============

Qt GameEnabler provides a simple framework for game developers, enabling the 
use of native OpenGL� ES 2.0 code within a Qt application. Qt GameEnabler does 
not utilise QtOpenGL but overrides Qt's own rendering and replaces it with 
native OpenGL. This enables applications to achieve maximum performance for 
just their own use. An application created with Qt GameEnabler will run on all 
devices supporting OpenGL ES 2.0. In addition, Qt GameEnabler provides a 
lightweight, easy-to-use audio framework with rich features.

The three main parts of Qt GameEnabler are:

1. GE::GameWindow: A QGLWidget-like class which allows the inheriter to use
   real OpenGL ES 2.0 instead of encapsulated QtOpenGL. The window will always
   be full-screen and without any compositing enabled: Everything is rendered
   directly on the screen. This prevents the user from using Qt's UI
   functionality, but other parts of it are still usable. For example, QImage
   can be used for loading GL textures.

2. Audio framework: A set of classes providing a very simple and easy-to-use
   system for loading WAV files as audio buffers and playing them with dynamic
   attributes (speed, volume, and so on). Audio playback is implemented using
   custom mixing and a single instance of QAudioOutput in either pull or push
   mode.

3. QML audio plug-in: QML extension plug-in which uses the audio framework to
   provide simple AudioBuffer, AudioEffect, and AudioMixer elements for use
   with QML

This framework has been tested on Symbian^3, Maemo 5 (Nokia N900),
and MeeGo 1.2 Harmattan (Nokia N9 and Nokia N950). In addition, the framework 
supports desktop platforms with OpenGL ES 2.0 emulation libraries (PowerVR), 
and has been tested on Windows XP and Windows 7.

This project is hosted in a Nokia Developer Project at:
http://projects.developer.nokia.com/qtgameenabler

For more information about the implementation, see the project wiki page:
http://projects.developer.nokia.com/qtgameenabler/wiki


PREREQUISITES
-------------------------------------------------------------------------------

- Qt basics
- OpenGL basics


IMPORTANT CLASSES
-------------------------------------------------------------------------------

GameWindow: The QGLWidget replacement with native OpenGL ES 2.0

AudioSource: An interface from which audio data can be pulled. All of the
playing is done via this class in GE::Audio. Custom audio sources must also be
inherited from this interface.

AudioBuffer: A class to contain a single audio buffer (for example, a single
audio file, such as WAV). The audio buffer itself is not able to play
anything, it only contains the audio data.

AudioBufferPlayInstance: A class derived from IAudioSource which points to an
AudioBuffer and can provide its audio data via IAudioSource's pull
functionality

AudioMixer: A helper class which contains a list of IAudioSources and methods
to manipulate them. All of the items in this list are mixed together when the
mixer's pullAudio is called.

AudioEffect: An interface for audio effects, such as echo, which can be 
applied to the audio buffer or mixer output. Current implementation includes 
cut-off (with resonance) and echo effects.

PushAudioOut/PullAudioOut: Audio output classes. PullAudioOut tries to provide
lower latency by using partial buffer upgrade.

AudioPlugin: Use this to register the QML extension plug-in which provides 
simple AudioBuffer, AudioEffect, and AudioMixer elements for QML.


EXAMPLES
-------------------------------------------------------------------------------

The project contains two examples which demonstrate the use of Qt GameEnabler.
The Qt GameEnabler Test example is a simple application that utilises both the 
OpenGL and the audio features of Qt GameEnabler. The example is located in the 
folder 'examples/qtgameenablertest'.

The Qt GameEnabler QML Audio Test example demonstrates the use of the QML 
audio plug-in. While the application does not utilise OpenGL, the user 
interface is implemented with QML code. The example is located in the folder 
'examples/qtgameenablerqmlaudiotest'.


PROJECT FOLDER STRUCTURE
-------------------------------------------------------------------------------

 |
 |- examples        The root folder of the example applications demonstrating
 |  |               the use of Qt GameEnabler
 |  |
 |  |- bin          Compiled example binaries
 |  |
 |  |- qtgameenablerqmlaudiotest
 |  |  |
 |  |  |- audio     Contains the audio samples
 |  |  |
 |  |  |- gfx       Contains the graphics
 |  |  |
 |  |  |- qml       Contains QML source code
 |  |  |
 |  |  |- rsc       Contains the resource files
 |  |
 |  |- qtgameenablertest
 |     |
 |     |- graphics  Contains the graphics
 |     |
 |     |- sounds    Contains the audio samples
 |     |
 |     |- test_src  Contains the source code of the example
 |
 |- qtgameenabler   The root folder of the actual Qt GameEnabler source code.
 |  |               Contains the project files, the license information and
 |  |               this file (release notes).
 |  |
 |  |- features
 |  |
 |  |- icons        Contains the project icons
 |  |
 |  |- plugins      Contains the source code of the QML audio plug-in
 |  |
 |  |- src          Contains the source code of the OpenGL ES wrapper and the
 |                  audio framework
 
Note that some folders are omitted from the above graph.


BUILD & INSTALLATION INSTRUCTIONS
-------------------------------------------------------------------------------

Preparations
~~~~~~~~~~~~
Check that you have the latest Qt/Qt SDK installed in the development
environment and on the device.

Note: The Qt GameEnabler Test example application, which utilises OpenGL, can 
be compiled directly on any device with OpenGL ES 2.0 support, for example, 
Maemo or Symbian^3 devices. However, if you wish to compile it on some other 
platform - desktop Windows, for example - you must have external OpenGL ES 2.0 
emulation libraries. With Windows or Linux (32bit) desktop, you can use 
Khronos OpenGL ES 2.0 PC-emulation libraries from www.imgtec.com:
http://www.imgtec.com/powervr/insider/sdkdownloads/index.asp#GLES2

The Qt GameEnabler QML Audio Test example compiles and runs also on platforms 
without OpenGL ES 2.0 support.

Build & installation instructions using Qt SDK
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Compiling the examples;

1. Open the project file:
   File > Open File or Project, select examples.pro

2. Select target(s), for example Desktop and Symbian^3, and press the Finish
   button.

3. Compile the project. If you are building for Desktop, modify the 
   qtgameenabler.pri file's 'windows' section's GLES2 include and library 
   paths according to where you have installed the SDK:
   'INCLUDEPATH += /PowerVRSDK/Builds/OGLES2/Include' and
   'LIBS +=  -L/PowerVRSDK/Builds/OGLES2/WindowsPC/Lib' must point to valid
   locations.

4. You are now able to run the examples.


COMPATIBILITY
-------------------------------------------------------------------------------

Symbian, MeeGo 1.2 Harmattan, and desktop platforms.

Tested on:
- Nokia C6-01
- Nokia C7-00
- Nokia E6-00
- Nokia E7-00
- Nokia N8-00
- Nokia N900 (PR1.2, PR1.3 firmware)
- Nokia N9
- Nokia N950
- Windows XP
- Windows 7

Developed with Qt SDK 1.1.


LICENSE AND COPYRIGHT INFORMATION
-------------------------------------------------------------------------------

Copyright (c) 2011 Nokia Corporation.

See the license text file delivered with this project. The license file is 
also available online at:
http://projects.developer.nokia.com/qtgameenabler/browser/trunk/qtgameenabler/Licence.txt

OpenGL is a registered trademark and the OpenGL ES logo is a trademark of
Silicon Graphics Inc. used by permission by Khronos (http://www.khronos.org/).


VERSION HISTORY 
-------------------------------------------------------------------------------

2.0     Various improvements, QML audio plug-in implementation, and two new
        examples
1.1     Added MeeGo 1.2 Harmattan support
1.0.2   Minor modifications related to Symbian audio handling
1.0.1   Added Debian packaging files for Maemo target
1.0     First version